home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Windows Expert
/
Windows Expert.iso
/
network
/
helldivr.zip
/
HSEND.DOC
< prev
next >
Wrap
Text File
|
1992-08-16
|
15KB
|
334 lines
Helldiver Send Mail/News Interface
Version 1.03
Copyright (C) 1991-1992 Rhys Weatherley
1. INTRODUCTION.
This document describes how to use the Helldiver Send program HSEND.EXE to
send mail and news under Waffle. The Helldiver Newsreader executes this DOS
program as its final mailing and posting stage. In effect, Helldiver Send
provides an abstract interface for sending mail and news that is independent
of any particluar news/mail system. It is intended that other similar programs
will be written in the future by myself or others for other UUCP systems.
Normally the user of a mailer or newsreader would not need to use HSEND.EXE
directly - the mailer or newsreader would invoke HSEND.EXE itself.
Currently Helldiver Send supports Waffle 1.64 and 1.65.
Because this program could prove useful to other people's projects, HSEND.EXE
may be distributed free of charge with your own programs as long as either
this documentation file is included verbatim, or the following copyright and
warranty message pertaining to Helldiver Send is included in your own
documentation:
-------------------------------------------------------------------------------
Helldiver Send, Copyright (C) 1991-1992 Rhys Weatherley, rhys@cs.uq.oz.au
Permission to use, copy, and distribute this material for any purpose
and without fee is hereby granted, provided that the above copyright notice
and this permission notice appear in all copies, and that the name of Rhys
Weatherley not be used in advertising or publicity pertaining to this material
without specific, prior written permission. RHYS WEATHERLEY MAKES NO
REPRESENTATIONS ABOUT THE ACCURACY OR SUITABILITY OF THIS MATERIAL FOR ANY
PURPOSE. IT IS PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES.
-------------------------------------------------------------------------------
Please contact me via e-mail at rhys@cs.uq.oz.au if you have any further
queries about Helldiver Send, or would like the latest version.
Other people are welcome to write Helldiver Send clones conforming to this
specification for Waffle, or for other mail/news packages. Please contact me
if you wish to extend this specification in any way so everyone's programs can
keep the same interface. To be conformant to this specification, both the
command-line and control file formats described below must be adhered to.
2. COMMAND-LINE USAGE.
Helldiver Send has the following two command-line usage alternatives:
hsend (filename|-) command
hsend control-file
In the first case, the filename specified in the first argument (standard
input if "-") is fed to the command specified by the remaining arguments as
standard input. Usually the command has one of the forms:
rmail addresss ...
rnews
This usage requires that the message be fully formatted already, complete
with From:, Message-Id: lines, etc. It is not recommended that new programs
calling Helldiver Send use this option. It is provided exclusively for
backwards-compatibilty with an earlier version of Helldiver Send that had a
limited audience. The current version runs Waffle's RMAIL.EXE or RNEWS.EXE
programs which must be on the PATH. Conformant implementations may interpret
"rmail" and "rnews" (in either case) as invoking the local mail and news
transmission facilities, whatever they may be.
The second usage above is the recommended usage for all callers of Helldiver
Send and conformant clones. The single argument specifies a control file
containing commands telling Helldiver Send how to transmit a mail or news
message. The next section describes the legal commands. An extensive,
albeit atypical, example control file follows:
File: f:\waffle\temp\msgaaba.tmp
From: rhys
From-name: Rhys Weatherley
Newsgroups: news.groups,news.admin
Mod-newsgroup: comp.archives mod@machine.domain.edu
Mod-newsgroup: comp.risks mod@risks.domain.edu
Local-newsgroup: 0.admin d:\news\local\0\admin
Local-newsgroup: 0.talk d:\news\local\0\talk
Followup-To: news.groups,news.admin
Followup-To-local: 0.talk
To: peter
Cc: paul
Cc: mary
Bcc: rhys
X-Mailer: Helldiver 1.04 (Waffle 1.64)
Append: f:\waffle\user\rhys\outbox
Sig: f:\waffle\user\rhys\sig
Lines: 40
Ref-groups: news.groups,news.admin,comp.archives,comp.risks
Distribution: aus
Dead-letters: f:\waffle\user\rhys\dead
Software: Waffle 1.64
Approved-for: john@nowhere.com (John Citizen)
Expires: 76757576
Control: cancel <.....>
Ignore: Newsgroup
Ignore: Crossposted-To
Ignore: Follow
Tempdir: f:\waffle\temp
Delete: no
Delete-control: no
Subject: PROGRAM.ZIP - a little useless program (Part 02/05)
Reply-To: rhys@cs.uq.oz.au
3. CONTROL FILE COMMANDS.
This section describes the commands that may be specified in a control file.
The ordering of command lines is not important. More than one message can
be specified in the same control file by separating the relevant sections with
a line containing a single "-" character. Unknown commands are ignored.
The meaning of each section is as follows: if there is a "To:", "Cc:" or "Bcc:"
line, then a mail message is sent. If there is a "Newsgroups" line, then a
news message is posted. If there is a "Local-newsgroup" line is specified,
then a message is posted to a local newsgroup. If there is a "Mod-newsgroup"
line, then a mail message is sent for a moderated newsgroup. Each of the
above may be mixed to send more than one message at once. Helldiver Send
avoids sending the final messages with a mixture of normal, local and
moderated groups. In particular, a final message posted to a normal
newsgroup doesn't contain any local or moderated newsgroup names, and a
final message posted to a moderated newsgroup must not contain any other
newsgroup names, including other moderated groups.
It is unclear as to whether Helldiver Send's behaviour with a mixture of
normal, local, and moderated groups is consistent with current USENET
practice in all cases. This may change in future versions, but conformant
implementations must still understand the "Newsgroups", "Local-newsgroup"
and "Mod-newsgroup" control file commands.
If an RFC-822 or RFC-1036 compliant header line is specified below, then it
should be removed from the original message file before copying the message
file to the final message. The input message file specified by the "File:"
command must consist of zero or more header lines, followed by a blank line
and the body of the message. If a header is implicitly specified by one of
the commands below, it doesn't need to be included in the original message,
though it can be: it will just be ignored.
Append:
If present, this command specifies a file to append the initial message
(specified by "File:") to. This is useful if a user has requested that
all their messages be saved in a file before transmission.
Approved-for:
If present, this command tells Helldiver Send to use the argument as
the "From:" line for the final message, and to use the "From:" command
as the user-id for the user approving the message, and the "Sender:"
name. The "Approved:" line always has the form "user@host" where
"host" is derived externally to Helldiver Send (in the case of Waffle,
it is specified in the STATIC file). This is a semi-security measure
to ensure that e-mail names of user's on a different site may not be
inserted into the "Approved:" line. Helldiver Send automatically
removes any "Approved:" lines in the original message file to prevent
bypassing this security feature.
Bcc:
Specify the e-mail address of a blind carbon-copy recipient of a
mail message. Only one recipient may be specified on the line,
but more than one "Bcc:" line may be given.
Cc:
Specify the e-mail address of a carbon-copy recipient of a mail
message. Only one recipient may be specified on the line, but
more than one "Cc:" line may be given.
Control:
The text of the "Control:" line in the final message. Note that
supporting this command can be a _big_ USENET security risk. It is
recommended that friendly front-end user interfaces not use this
command, except maybe for the cancellation of a user's articles.
Conformant Helldiver Send clones may wish to inhibit this command
or restrict the control messages that can be generated using it.
Ultimately it is not possible to stop a system administrator
generating bogus control messages by directly talking to RNEWS,
but other users should be restricted from its use.
Dead-letters:
The name of a file to append messages to that could not be delivered
for any reason. The Helldiver Newsreader uses the file "DEAD" in the
user's home directory for this purpose. If this command is not
present, dead letters are merely discarded.
Delete:
If present, it indicates if the message file specified by "File:"
should NOT be deleted after message delivery. The default is to
delete the file. The argument should be "no" in lower case for
upwards compatibility with future Helldiver Send versions. Currently
the argument is ignored, and file is deleted if this command is
not present.
Delete-control:
Similar to "Delete:", but indicates if the control file should be
deleted after delivering all messages. This command must occur in
the first section if there is more than one separated by "-" lines.
It is recommended that callers of Helldiver Send not specify "Delete"
or "Delete-control" but arrange for temporary files to be used for
both the message and control files. Thus, a single call on Helldiver
Send can stand-alone, with the calling program not needing to do
any clean-up afterwards. This is important in environments like
Microsoft Windows where it is difficult to detect when a child process
(like running Helldiver Send to send a message) has terminated and
clean up the temporary files in the parent: all clean-ups are done
in Helldiver Send itself.
Distribution:
A comma-separated list of USENET distributions to place into the
final message's "Distribution:" line.
Expires:
An expiry date in Unix datetime format (i.e. the number of seconds
since 1 Jan 1970).
File:
Specifies the name of the file containing the message. The header is
separated from the body by a single blank line. The header may
contain some header fields that are automatically generated by other
control file commands, which are ignored when the final message is
generated.
Followup-To:
Specifies a comma-separated list of newsgroups to enter into the
final message's "Followup-To:" line.
Followup-To-local:
Specifies a comma-separated list of local newsgroups to enter into
the "Followup-To:" line (in addition to any "Followup-To" groups) for
messages posted to local newsgroups.
From:
Specify the user-id of the user the message is from. If the
"Approved-for:" line is also present, this specifies the user-id of
the user approving the message and "Approved-for:" gives the text
of the final message's "From:" line.
From-name:
Real name of the user to be inserted into the "From:" line of the
final message. The final "From:" line will have the form
"user@host (real name)" or "real name <user@host>" depending on
the implementation. Helldiver Send uses the first form. Note that
the supplied real name may contain unmatched parentheses or angle
brackets, so a conformant implementation should drop or re-match
unmatched pairs. Matched pairs should still be copied to the
final message though.
Ignore:
The name of a header field to ignore when generating the final
message. i.e. if the header field appears in the original message
file, then that line will be removed.
Lines:
Number of lines in the body of the message. If this command is not
present, then no "Lines:" header is inserted into the final message.
Note the comments for the "Sig:" command when using this command.
Local-newsgroup:
Name of a local newsgroup and the corresponding spool directory. It
is assumed that the article is to be stored into the directory as a
numbered file, and no other processing is required. On some systems,
"Newsgroups:" could be used instead of "Local-newsgroup:". This
is possible under Waffle, but since RNEWS.EXE is executed, then the
FEEDS file must be edited to stop local newsgroups being fed to other
sites. Note that no checking is done to see if local newsgroups in
Waffle have overflowed the "/keep" setting.
Mailer-ident:
A short string of characters that can be inserted into the final
message's "Message-Id:" field if the program desires to. The default
string is an empty string. For example, the Helldiver Newsreader
sets this command to "hxyyh" where "x.yy" is the current newsreader
version, so that Message-Id's have the form "<ABCDEFhxyyh@host>".
Use of this command can help isolate software versions that generate
invalid news and mail messages by inspecting the Message-Id. It is
not necessary that all conformant implementations use this command.
Mod-newsgroup:
Name of a moderated newsgroup and the e-mail address to send the
posting to.
Newsgroups:
A comma-separated list of newsgroups to post the message to.
Ref-groups:
If present, then the text of this line is output as the "Newsgroups:"
line in any mail messages. It is intended to be used for replies to
news postings so that the newsgroups appear in the final reply.
Reply-To:
A fully qualified e-mail address to be inserted into the "Reply-To:"
line of the final message.
Sig:
If present, specifies the name of a file to be appended to the final
message as the user's signature. Note that if the "Lines:" option
is also present, then the lines of the signature may not be included
in the final count, so it is usually better to append the signature
in the originating program if a "Lines:" header is desired.
Software:
The name of the software to use for mailing or posting the final
messages. At present, Helldiver Send recognises "Waffle 1.64" and
"Waffle 1.65" in this command as indicating that Waffle 1.64 (or 1.65)
should be used for sending mail and news. Contact rhys@cs.uq.oz.au
for details on other identifiers, and for registering your own
identifiers. If "Software:" is not recognised, then the program
can either ignore or continue to process the message - this behaviour
is not defined by this specification.
Subject:
If present, then it indicates a new subject to be used to replace the
subject in the original message. This is convenient for indicating
the part number for multi-part messages by overriding the user's
entered subject for each of the parts.
Tempdir:
This command is mandatory and specifies a directory that temporary
files can be created in.
To:
Specify the e-mail address of a recipient of a mail message. Only
one recipient may be specified on the line, but more than one "To:"
line may be given.
X-Mailer:
An optional comment line. The contents of this line are copied into
an "X-Mailer:" line in the final message. Usually this is the name
and version of the program calling Helldiver Send.
Please contact the author at rhys@cs.uq.oz.au if you have any further queries.